<?xml version="1.0" encoding="UTF-8"?>
<html filename="docs/BSAXExt/IBufferedEntityResolver2.html">
<body>
<a id="#top"/>
<h1>
	                Interface Summary : IBufferedEntityResolver2 </h1> Extended interface for mapping external entity references to input
 sources, or providing a missing external subset.  The
 <a href="../BSAX/IBufferedXMLReader.html#setEntityResolver">IBufferedXMLReader.setEntityResolver</a>
 method is used to provide implementations of this interface to parsers.
 When a parser uses the methods in this interface, the
 <a href="../BSAXExt/IBufferedEntityResolver2.html#resolveEntity">IBufferedEntityResolver2.resolveEntity</a>
 method (in this interface) is used <em>instead of</em> the older (SAX 1.0)
 <a href="../BSAX/IBufferedEntityResolver.html#resolveEntity">IBufferedEntityResolver.resolveEntity</a>
 method.

 <blockquote>
 <em>This module, both source code and documentation, is in the
 Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
 </blockquote>

 <p>If a SAX application requires the customized handling which this
 interface defines for external entities, it must ensure that it uses
 an IBufferedXMLReader with the
 <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag
 set to <em>true</em> (which is its default value when the feature is
 recognized).  If that flag is unrecognized, or its value is false,
 or the resolver does not implement this interface, then only the
 <a href="../BSAX/IBufferedEntityResolver.html">IBufferedEntityResolver</a> method will be used.
 </p>

 <p>That supports three categories of application that modify entity
 resolution.  <em>Old Style</em> applications won't know about this interface;
 they will provide an IBufferedEntityResolver.
 <em>Transitional Mode</em> provide an IBufferedEntityResolver2 and automatically
 get the benefit of its methods in any systems (parsers or other tools)
 supporting it, due to polymorphism.
 Both <em>Old Style</em> and <em>Transitional Mode</em> applications will
 work with any SAX2 parser.
 <em>New style</em> applications will fail to run except on SAX2 parsers
 that support this particular feature.
 They will insist that feature flag have a value of &quot;true&quot;, and the
 IBufferedEntityResolver2 implementation they provide  might throw an exception
 if the original SAX 1.0 style entity resolution method is invoked.
 </p>

 <p>For reasons of generality and efficiency, strings that are returned
 from the interface are declared as pointers (PSAXChar) and lengths.
 This requires that the model use procedural out parameters rather
 than functions as in the original interfaces.</p>

<br/><b>See : </b> <a href="../BSAX/IBufferedXMLReader.html#setEntityResolver">IBufferedXMLReader.setEntityResolver</a>

<br/><b>Since : </b> SAX 2.0 (extensions 1.1 alpha)
<h2>
	              Methods
	            </h2>
<div style="padding-left:10px">
<a href="#getExternalSubset">
	                  function
	                 getExternalSubset(PSAXChar, Integer, PSAXChar, Integer) : IInputSource</a>
<br/>
<a href="#resolveEntity">
	                  function
	                 resolveEntity(PSAXChar, Integer, PSAXChar, Integer, PSAXChar, Integer, PSAXChar, Integer) : IInputSource</a>
<br/>
</div>
<br/>
<hr width="100%"/>
<a name="#getExternalSubset">
<p>
<b>function</b> getExternalSubset( name : PSAXChar;  nameLength : Integer;  baseURI : PSAXChar;  baseURILength : Integer) : IInputSource; </p>
</a> <p>Allows applications to provide an external subset for documents
 that don't explicitly define one.  Documents with DOCTYPE declarations
 that omit an external subset can thus augment the declarations
 available for validation, entity processing, and attribute processing
 (normalization, defaulting, and reporting types including ID).
 This augmentation is reported
 through the <a href="../BSAXExt/IBufferedLexicalHandler.html#startDTD">startDTD</a> method as if
 the document text had originally included the external subset;
 this callback is made before any internal subset data or errors
 are reported.</p>

 <p>This method can also be used with documents that have no DOCTYPE
 declaration.  When the root element is encountered,
 but no DOCTYPE declaration has been seen, this method is
 invoked.  If it returns a value for the external subset, that root
 element is declared to be the root element, giving the effect of
 splicing a DOCTYPE declaration at the end the prolog of a document
 that could not otherwise be valid.  The sequence of parser callbacks
 in that case logically resembles this:</p>

 <pre>
 ... comments and PIs from the prolog (as usual)
 startDTD('rootName', source.getPublicId(), source.getSystemId());
 startEntity ('[dtd]');
 ... declarations, comments, and PIs from the external subset
 endEntity ('[dtd]');
 endDTD();
 ... then the rest of the document (as usual)
 startElement (..., 'rootName', ...);
 </pre>

 <p>Note that the InputSource gets no further resolution.
 Implementations of this method may wish to invoke
 <a href="../BSAXExt/IBufferedEntityResolver2.html#resolveEntity">resolveEntity</a> to gain benefits such as use
 of local caches of DTD entities.  Also, this method will never be
 used by a (non-validating) processor that is not including external
 parameter entities. </p>

 <p>Uses for this method include facilitating data validation when
 interoperating with XML processors that would always require
 undesirable network accesses for external entities, or which for
 other reasons adopt a &quot;no DTDs&quot; policy.
 Non-validation motives include forcing documents to include DTDs so
 that attributes are handled consistently.
 For example, an XPath processor needs to know which attibutes have
 type &quot;ID&quot; before it can process a widely used type of reference.</p>

 <p>
      <strong>Warning:</strong> Returning an external subset modifies
 the input document.  By providing definitions for general entities,
 it can make a malformed document appear to be well formed.
 </p>

<br/><b>Parameter : </b> name Identifies the document root element.  This name comes
  from a DOCTYPE declaration (where available) or from the actual
  root element.
<br/><b>Parameter : </b> nameLength The length of the name buffer.
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Parameter : </b> baseURI The document's base URI, serving as an additional
  hint for selecting the external subset.  This is always an absolute
  URI, unless it is an empty string because the IXMLReader was given an
  IInputSource without one.
<br/><b>Parameter : </b> baseURILength The length of the baseURI buffer.
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.

<br/><b>Result : </b> An InputSource object describing the new external subset
  to be used by the parser, or nil to indicate that no external
  subset is provided.

<br/><b>Exception : </b> ESAXException Any SAX exception.
<br/>
<p>
<a href="#top">Top</a>
</p>
<hr width="100%"/>
<a name="#resolveEntity">
<p>
<b>function</b> resolveEntity( name : PSAXChar;  nameLength : Integer;  publicId : PSAXChar;  publicIdLength : Integer;  baseURI : PSAXChar;  baseURILength : Integer;  systemId : PSAXChar;  systemIdLength : Integer) : IInputSource; </p>
</a> <p>Allows applications to map references to external entities into input
 sources, or tell the parser it should use conventional URI resolution.
 This method is only called for external entities which have been
 properly declared.
 This method provides more flexibility than the <a href="../BSAX/IBufferedEntityResolver.html">IBufferedEntityResolver</a>
 interface, supporting implementations of more complex catalogue
 schemes such as the one defined by the
 <a href="http://www.oasis-open.org/committees/entity/spec-2001-08-06.html">
 OASIS XML Catalogs</a> specification.</p>

 <p>Parsers configured to use this resolver method will call it
 to determine the input source to use for any external entity
 being included because of a reference in the XML text.
 That excludes the document entity, and any external entity returned
 by <a href="../BSAXExt/IBufferedEntityResolver2.html#getExternalSubset">getExternalSubset</a>.
 When a (non-validating) processor is configured not to include
 a class of entities (parameter or general) through use of feature
 flags, this method is not invoked for such entities.</p>

 <p>Note that the entity naming scheme used here is the same one
 used in the <a href="../BSAXExt/IBufferedLexicalHandler.html">IBufferedLexicalHandler</a>, or in the
 <a href="../BSAX/IBufferedContentHandler.html#skippedEntity">IBufferedContentHandler.skippedEntity</a>
 method. </p>

<br/><b>Parameter : </b> name Identifies the external entity being resolved.
  Either '[dtd]' for the external subset, or a name starting
  with '%' to indicate a parameter entity, or else the name of
  a general entity.  This is never empty when invoked by a SAX2
  parser.

<br/><b>Parameter : </b> nameLength The length of the name buffer.
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Parameter : </b> publicId The public identifier of the external entity being
  referenced (normalized as required by the XML specification), or
  an empty string if none was supplied.
<br/><b>Parameter : </b> publicIdLength The length of the publicId buffer.
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Parameter : </b> baseURI The URI with respect to which relative systemIDs
  are interpreted.  This is always an absolute URI, unless it is
  nil because the XMLReader was given an IInputSource without one.
  This URI is defined by the XML specification to be the one
  associated with the '&lt;' starting the relevant declaration.
<br/><b>Parameter : </b> baseURILength The length of the baseURI buffer.
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.
<br/><b>Parameter : </b> systemId The system identifier of the external entity
  being referenced; either a relative or absolute URI.
  This is never empty when invoked by a SAX2 parser; only declared
  entities, and any external subset, are resolved by such parsers
<br/><b>Parameter : </b> systemIdLength The length of the systemId buffer.
   The value may be -1 which indicates that the buffer is
   null-terminated. If the value is 0 then the buffer may be nil.

<br/><b>Result : </b> An IInputSource object describing the new input source to
  be used by the parser.  Returning nil directs the parser to
  resolve the system ID against the base URI and open a connection
  to resulting URI.

<br/><b>Exception : </b> ESAXException Any SAX exception.
<br/>
<p>
<a href="#top">Top</a>
</p>
</body>
</html>